pp108 : Toolbar (Objects)

Toolbar (Objects)

  

The Toolbar control is an additional feature that is not available as a control in the XForms Toolbox. Using the Toolbar, you can add common buttons that apply to all the controls in the XForm.

The following button types are available on the Toolbar:

  • Standard Toolbar Item / button: Refers to the Save and Print buttons on the toolbar. The Save button helps synchronize all models available in the XForm. The Print button enables printing of the XForm at runtime.
  • Other Toolbar Item / button: Refers to other buttons that you can add to the toolbar.

The only difference between a toolbar item and a toolbar button is its appearance. A toolbar button functions and appears as a standard button.

 

Properties, Events, and Methods of the Controls

The toolbar items and toolbar buttons have certain properties, events, and methods. These properties define their behavior and can be set through the property page of the button or item respectively, or programmatically using the APIs.

Table 1. List of Properties for the Toolbar buttons

Design-time property

Runtime property

Description

ID

  

Sets the string that identifies the control on an XForm. If not specified, a unique ID is automatically generated.

Class Name

className

Sets or retrieves the class name applied on the control.

Tooltip

title

Sets the tool tip that appears on a control when the mouse is moved over it. Programmatically, this property is set by specifying the title property of the control.

Image (only for the toolbar item)

src

Sets the location of the image to be displayed on the control.

Caption (only for the toolbar item)

  

Sets the text to be displayed as a tool tip for the toolbar button.

Type (only for the toolbar item)

  

Sets the type of the toolbar button.

  • Default: Displays a button as is.
  • Dropdown: Displays a drop-down list with the toolbar button.
  • Toggle: Enables a toggle option for the toolbar button.

Access Key

  

Sets the key that can be used to access the toolbar button. The key specified is to be used in combination with the Alt key at runtime, such as Alt+<access key>. In case of the Firefox browser, use Alt+Shift+<access key>.

Task Part

  

Sets whether the toolbar button can be associated with a task part. For details, see Property Sheet of Controls, Regions, and AppPalettes and Creating a Task Part for a Control.
Table 2. List of Events for the Toolbar Buttons

Event

Description

Click

This event is activated when you click the button.

onbeforesave (for the Save button only)

This event is activated before the data models are synchronized with the backend, when you click the Save button.

onaftersave (for the Save button only)

This event is activated after the data models are synchronized with the backend, when you click the Save button.

onbeforeprint (for the Print button only)

This event is activated before the print dialog is invoked, after you click the Print button.

onafterprint (for the Print button only)

This event is activated after the print dialog is closed. The print dialog is invoked after you click the Print button.
Table 3. List of Methods for the Toolbar Buttons

Method

Description

disable()

This method disables the button on which it is invoked.

enable()

This method enables the button on which it is invoked.

hide()

This method hides the control and all associated child controls.

isEnabled()

This method retrieves the value that denotes whether the button is enabled or not.

show()

This method makes the control and its child controls visible.
Table 4. List of Properties for Toolbar

Design-time property

Runtime property

Description

ID

  

Sets the string that identifies the toolbar on an XForm. If not specified, a unique ID is automatically generated.

Class Name

className

Sets or retrieves the class name applied on the control.

Orientation

  

Sets the position of the toolbar. Possible options are Top, Bottom, Left, and Right.

Scroll-By

  

Sets the type of scrolling action to be used to view buttons on the toolbar.

  • Default: Displays all toolbar buttons.
  • Roller: Displays a roller to navigate through toolbar buttons.

Icon Size

  

Sets the size of icons used in the toolbar.

  • Set as Default to use a simple image as is.
  • Set as Small to use the smallest multi-size icons.
  • Set as Medium to use medium multi-size icons.
  • Set as Large to use the largest multi-size icons.
Table 5. List of Methods for Toolbar

Method

Description

addItem

This method adds an item to the existing toolbar. For details about this method, see Toolbar.

addListener()

This method registers the control to receive notifications for an event.

addSeparator()

This method adds a separator to the existing toolbar. For details about this method, see Toolbar.

removeListener()

This method unregisters the control to cease receiving notifications for its events.
Guidelines to print more effectively
  • Before printing, go to File > Page Setup in the browser.
  • Set the page properties such as page size, page orientation, and page margins.
  • You can define print settings for images and background colors in the Page Setup dialog box. For example, in Internet Explorer, select File > Print Preview > Page Setup or set the advanced printing options Tools > Options > Advanced > Printing.
    Note: Print option is a user setting that you need to enable for each browser on every system. For more details on this feature, see the Epson printer help page.
  • Use PDF drivers, such as Cute PDF, Nitro PDF, or Primo PDF to test and print the XForms. Installing and printing PDF output through any of these drivers will emulate most paper sizes, and the output can be previewed digitally, thus saving paper.

Forms that have free layouts (absolute positions defined for user interface elements) may not print properly. This is because free layouts use absolute positioning, and this pixel (or any other unit) may not fit properly on your page area as defined by the printer. This depends on many factors that are considered when designing the form. It is recommended to use Vertical or Horizontal layouts, as it ensures a robust XForm that can be viewed on various screen resolutions. If free layout is used, test it and ensure the dimensions fit the intended page area.